Cream of the Crop 22/Cream of the Crop 22.iso/bbs/g5109b.zip/G5.ZIP/TEXT/XPORTS.TXT

Text File | 1996-11-27 | 19KB | 325 lines

                              ──══ Galaxy 5 ══──
                      Copyright (c) 1996 Thomas J. Smith

     ────────────────────────────────────────────────────────────────────
      This text file explains the use of Xports, how to install and use
      them, and how to go about creating your own!
     ────────────────────────────────────────────────────────────────────
      For a complete listing of data file structures, formats of all of
      the drop files that G5 creates, and a complete list of color, and
      other codes, unzip the G5_STRUC.ZIP archive. Everything 3rd party
      programmers need is located in this archive!
     ────────────────────────────────────────────────────────────────────


                                 HOW THEY WORK
     ────────────────────────────────────────────────────────────────────
      In order to explain this in the simplest way, I will use an
      example. Lets say Joe SysOp just downloaded an Xport called
      "Hermans World." First, Joe unzips the file he just downloaded to
      a temporary directory (or the directory he wishes the Xport to be
      installed to). Then Joe will read the docs that came with the .ZIP
      file first (or will he?). In the docs, Joe will find that all he
      needs to do to install this Xport, is run the INSTALL.EXE program
      included with the .ZIP file (or other installation method). The
      install program then puts all the necessarry files in their proper
      places, and writes the needed info to the XPORTS.DAT file in Joes
      main Galaxy 5 directory.
     ────────────────────────────────────────────────────────────────────
      Now to use the Xport, Joe logs on to Galaxy 5 either locally, or
      by logging on to his BBS locally, and running the game from there.
      From the main menu (Lexor Street, or whichever planet he is on),
      Joe will choose the option, "(X)port to another place." Then he is
      taken to a menu listing all of the Xports he has installed. If he
      only installed one Xport, then only the name of that one Xport
      will be listed as number (1). Joe then presses 1 to go to this
      Xport, and wala! Thats all there is to it. After Joe is done using
      the Xport, Galaxy 5 reloads, and picks up from the Xport menu
      where it left off, and deducts the time that Joe was in the Xport
      from his time left in the game!
     ────────────────────────────────────────────────────────────────────
      Then later (or right after trying it), if Joe finds that he does
      not like this Xport, he runs the UNINSTAL.EXE program that came
      with the Xport (or whatever program the Xports docs point him
      to), and the game is "uninstalled!"
     ────────────────────────────────────────────────────────────────────


                                     Q & A
     ────────────────────────────────────────────────────────────────────
       Q. What is an Xport?
      ----------------------
       A. An Xport is an external program (door) created by third
          party programmers for use in your Galaxy 5 game. They can
          be run directly from within the game, without any special
          setup on the SysOps part!
     ────────────────────────────────────────────────────────────────────
       Q. Where can I find an Xport?
      -------------------------------
       A. I currently have a collection of a few Xports and utilities
          at my web site. Both those created by me, and those created by
          other authors. Visit
          http://www.geocities.com/SiliconValley/Heights/2233

          Depending on how well Galaxy 5 does with popularity, it may or
          may not be hard to find an Xport.  However, I have created a
          freeware Xport named "The Inscribers Guild." It allows players
          to personalize their Armour, Weapon, and Space Craft at a
          price the SysOp sets. SysOp can also disallow personalizing of
          any of the three items mentioned.  Look for SCRIBE??.ZIP
          (where ?? is the version number).
     ────────────────────────────────────────────────────────────────────
       Q. If I find one, how do I set it up?
      ---------------------------------------
       A. It should be extremely simple to set up. As a ground rule,
          any Xport created by a third party programmer, must come
          with an easy to use install program, and easy to use
          "uninstall" program in case the SysOp does not like it, or
          needs to remove it for some reason. The SysOp installing the
          Xport, should not have to do anything else but run the
          INSTALL program that comes with the Xport!
     ────────────────────────────────────────────────────────────────────
       Q. What if an Xport I installed doesn't work properly?
      --------------------------------------------------------
       A. Read the docs that came with it. If the author(s) of the Xport
          provides support for the program, then follow their
          instructions on how to obtain that support. It is beyond my
          ability to help with problems concerning someone elses
          program! :) If all else fails, remove the Xport from your
          game. If the Xport just happened not to come with an
          uninstall program, then remove the two lines in the
          XPORTS.DAT file that pertain to that Xport.
     ────────────────────────────────────────────────────────────────────
       Q. I write doors, how can I make an Xport?
      --------------------------------------------
       A. If the door writing kit that you use supports the Quick BBS
          drop file format (DORINFO*.DEF where * is the node number),
          then you may already have what you need to write your own
          Xport! Galaxy 5 creates 3 drop files before running an Xport,
          one of which is a DORINFO*.DEF compatible drop file. Figure
          out some way to have your Xport read this drop file (located
          in the TEMP subdirectory), and it -should- be all you need!
          If this doesn't work for you, if you have the source code to
          your door writing kit, then you may be able to add a procedure
          or function that will read the door info that it needs from
          one of the G5 drop files. Other door writing kits that are
          directly supported are UrDoor, and the DDplus door driver kit.
          Read the next section, "Creating Your Own Xports." It explains
          everything you need to know!
     ────────────────────────────────────────────────────────────────────


                           CREATING YOUR OWN XPORTS
     ────────────────────────────────────────────────────────────────────
      ** Unzip the G5_STRUC.ZIP archive!! It contains everything you
         need to know!!! ;>
     ────────────────────────────────────────────────────────────────────
      If you do not program in Turbo Pascal, and would still like to
      make an Xport for Galaxy 5, then refer to the G5_STRUC.ZIP
      archive. Galaxy 5 creates a plain text drop file containing the
      callers full record information, in which you can make changes to,
      and Galaxy 5 will accept the changes upon returning from your
      Xport.
     ────────────────────────────────────────────────────────────────────
      Before your creation(s) can be "officially" called Xports, you
      must follow these 3 simple rules:
     ────────────────────────────────────────────────────────────────────
      1 ■ It must come with an easy to use install program, and an easy
          to use uninstall program. These can be implemented as separate
          .EXE's, or as command line switches in your game, or whatever.
          What the install program must do, is place its game files in
          the proper directory (preferably its own directory off of the
          main Galaxy 5 directory), and write its needed two lines to
          the XPORTS.DAT file located in the main Galaxy 5 directory.
          The XPORTS.DAT file, is a regular text file, listing the name
          of your Xport as it will be shown to callers first, and then
          the command line you want passed to your door when a player
          uses the Xport on the second line. Here is an example,

          ~0B~T~01~he ~0B~I~01~nscribers ~0B~G~01~uild
          C:\DOORS\GALAXY5\SCRIBES\SCRIBES.EXE ~UN~

          In the above example, the characters in between the tilde (~)
          signs are codes used by Galaxy 5. ~01~ tells G5 to set the
          color following to blue, ~0B~ tells G5 to set the color
          following to light cyan (see "Galaxy 5 Codes" for a complete
          list of color codes), and ~UN~ is a user variable. In this
          case, it will be replaced by the node number the current
          caller is on. So the command that will go into the batch file
          that calls this Xport, would be,
          C:\DOORS\GALAXY5\SCRIBES\SCRIBES.EXE 1, if the caller was on
          node 1. There are many other user variables you can use in
          the XPORTS.DAT file to use on your Xports command line, and
          they are all listed below in the section, "Galaxy 5 Codes."
     ────────────────────────────────────────────────────────────────────
      2 ■ Your Xport must get all of its caller info from one or more of
          4 sources,
                    a. The user variables placed in the XPORTS.DAT file
                       on the command line for your Xport.

                    b. The DROPFILE.* file which G5 creates for each
                       caller online (* is the callers node number).

                    c. From the NODE*.DAT file which G5 also creates for
                       each caller online (again, the * will be the node
                       number that the caller is on).

                    d. The DORINFO*.DEF file which G5 also creates for
                       each caller online. Same as the above two, the
                       star will be the node number.
     ────────────────────────────────────────────────────────────────────
      All of the three drop files created, are placed in the TEMP
      subdirectory. So if your Galaxy 5 game is in C:\DOORS\GALAXY5,
      then the drop file directory would be C:\DOORS\GALAXY5\TEMP.
     ────────────────────────────────────────────────────────────────────
      The format of the three drop files created can be found in the
      G5_STRUC.ZIP archive. Your Xport must NOT read a BBS drop file!
     ────────────────────────────────────────────────────────────────────
      3 ■ Please do not charge more for your Xports than what it costs
          to buy Galaxy 5 (15 bucks).
     ────────────────────────────────────────────────────────────────────
      If you have no means of doing this with the door writing kit that
      you are using, then try to find some way to implement your own
      procedure to read the caller info from the DROPFILE.* drop file
      (or one of the others), instead of your door kit looking for the
      BBS drop file.
     ────────────────────────────────────────────────────────────────────
                                A FEW POINTERS
                               ----------------
      1 ■ Don't make an Xport that gives the players mucho amounts of
          "stuff." This makes the game no fun when the player has done
          everything they can possibly do before they are even half way
          through the game!

      2 ■ Try to keep a look and feel that the players are familiar
          with. This is not a must, but its no fun for a player to enter
          an Xport and be totally lost! At the least, make it easy to
          navigate.

      3 ■ Your Xports can do almost anything! Consider the fact that the
          game takes place in a futuristic space age setting. Using that
          you can have time tunnels that take callers back to medieval
          times, transporters that take them to other galaxies, a bus
          station that leads to your own planet, or just a new place on
          the planet they are on.  The only limit is your imagination!
     ────────────────────────────────────────────────────────────────────


                                GALAXY 5 CODES
     ────────────────────────────────────────────────────────────────────
      Listed here are all of the codes that you can use on the command
      line for your Xport in the XPORTS.DAT file. For a full, complete
      listing of all Galaxy 5 codes, unzip G5_STRUC.ZIP and read the
      G5_CODES.TXT file.
     ────────────────────────────────────────────────────────────────────
                                  Color Codes
                                 -------------
      Color codes can be used on the line in the XPORTS.DAT file that
      lists the name of your Xport, not on the command line for your
      Xport! Here is the format for color codes,
                                                ~BF~
                                                 │└Foreground color
                                                 └Background color

       Background Colors                     Foreground Colors
      -------------------                   -------------------
       0 = Black                             0 = Black
       1 = Blue                              1 = Blue
       2 = Green                             2 = Green
       3 = Cyan                              3 = Cyan
       4 = Red                               4 = Red
       5 = Magenta                           5 = Magenta
       6 = Brown (dark yellow)               6 = Brown (dark yellow)
       7 = Light Gray                        7 = Light Gray
       8 = Black (blinks foreground)         8 = Dark Gray (light black)
       9 = Blue (blinks foreground)          9 = Light Blue
       A = Green (blinks foreground)         A = Light Green
       B = Cyan (blinks foreground)          B = Light Cyan
       C = Red (blinks foreground)           C = Light Red
       D = Magenta (blinks foreground)       D = Light Magenta
       E = Brown (blinks foreground)         E = Light Yellow
       F = Light Gray (blinks foreground)    F = White
     ────────────────────────────────────────────────────────────────────
                                USER VARIABLES
                               ----------------
      These codes can be used to pass caller information to your Xport
      in the XPORTS.DAT file. Each user variable contains a U as the
      first character, and the second character will be whatever you
      want passed to your Xport. Listed below are the user variables.

      ~U*~
       │└Fill this in with one of the characters below
       └U (for user)

      E = Will be replaced with either TRUE or FALSE, for "Keep a log of
          errors?"
      I = Will be replaced by the IRQ number.
      C = Will be replaced by the COM port number.
      B = Contains the callers baud rate.
      F = Holds the users first name.
      L = Users last name.
      D = Full path and file name of DROPFILE.* file for this caller.
      P = Full path and file name of NODE*.DAT file for this caller.
      R = Full path and file name of DORINFO*.DEF file for this caller.
      N = Node number this caller is on.
     ────────────────────────────────────────────────────────────────────
      Here is an example using the user variables listed above. If I put
      this command line in the XPORTS.DAT file as the command line to be
      passed to my door,

      C:\DOORS\GALAXY5\XPORT.EXE ~UN~ ~UD~

      Then if a caller used the Xport from node 2, then the above
      example would be passed to my door looking like this,

      C:\DOORS\GALAXY5\XPORT.EXE 2 C:\DOORS\GALAXY5\TEMP\DROPFILE.2
     ────────────────────────────────────────────────────────────────────
      When a caller chooses to use an Xport from within the game, a file
      is created in the temp directory called XPORT*.BAT where * is the
      node number the caller is on. Galaxy 5 exits with an errorlevel of
      255. Then, in the G5.BAT file, it detects this errorlevel, and in
      turn, executes XPORT*.BAT. Then after XPORT*.BAT is done, Galaxy 5
      reloads, gathers how many minutes the caller was in the Xport, and
      subtracts those minutes from the callers time, so as to keep a
      proper balance in the callers time allowed in the door. Then the
      caller is returned back to the Xports menu, right where he/she
      left off. But you really needn't pay any attention to any of this
      to write an Xport, this is all done by Galaxy 5 with no help from
      you! :)
     ────────────────────────────────────────────────────────────────────


                           ALLOWING OVERNIGHT STAYS
     ────────────────────────────────────────────────────────────────────
      If you wish to allow players to stay the night in your Xport, then
      here is what you need to do...

      1) Upon exiting your Xport, first create a file named EXITGAME.#
         where # is replaced by the node number. This file does not have
         to contain anything special, in fact, it can even be a 0 byte
         file. Simply put, if it exists, then the game will exit upon
         returning from your Xport.

      2) Create a record in the XPORTINF.DAT file, located (or will be)
         in the DATA subdirectory. The format of this file is given in
         the G5_STRUC.PAS file located inside the G5_STRUC.ZIP file. If
         this file does not yet exist, then you must create it. If it
         does exist, then add a record to it for the current player,
         then forget about it. G5 will handle altering and removing the
         record as it continues with the player.

      3) Thats it! The game will exit when your Xport is finished, and
         the next time the caller plays G5, he/she will be taken directly
         to your Xport.

      I know this is not the best way, but I did not want to change the
      structure of the PLAYERS.DAT file (this would have been easiest).
      If I did that, then all Xports and utilities that use the
      PLAYERS.DAT file, would also have to be updated, and SysOps would
      not be able to use them until they were updated.
     ────────────────────────────────────────────────────────────────────


                                ■ END OF FILE ■